/**
 * <h3>ICampusNewsService</h3>
 * <p>校园新闻信息管理服务接口</p>
 *
 * <h3>功能描述</h3>
 * <p>定义校园新闻信息增删改查等基础业务操作，供实现类完成具体数据库交互逻辑</p>
 * <p>接口基于 MyBatis Plus 的 {@link IService} 扩展，统一规范数据访问层行为</p>
 * <p>支持新闻的创建、编辑、删除、查询等核心功能，包含分页查询和详细信息获取</p>
 *
 * <h3>元数据</h3>
 * <ul>
 *    <li>作者：郭强</li>
 *    <li>创建日期：2025年05月20日 21:15:20</li>
 * </ul>
 *
 * <h3>其他信息</h3>
 * <ul>
 *    <li>参考链接：<a href="https://example.com">官方网页</a></li>
 *    <li>示例代码：{@code new ICampusNewsService()} </li>
 * </ul>
 *
 * @apiNote 接口方法需保证事务一致性与线程安全；实际实现应避免直接new
 * @implSpec 继承自 {@link IService<CampusNewsDTO>}，扩展了按条件查询、按ID获取等方法
 * @since 1.0.0
 */

package com.dnndo.system.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.dnndo.system.domain.CampusNews;
import com.dnndo.system.domain.dto.CampusNewsDTO;
import com.dnndo.system.domain.dto.NewsDTO;
import com.dnndo.system.domain.vo.CampusNewsInfoVO;
import com.dnndo.system.domain.vo.NewsVO;

import java.util.List;

/**
 * 校园新闻服务接口
 */
public interface ICampusNewsService extends IService<CampusNewsDTO> {

    /**
     * 根据条件分页查询校园新闻列表
     * @param dto 新闻查询条件封装对象，包含标题、学校ID等过滤条件
     * @return List<CampusNews> 符合条件的新闻信息列表
     * @see com.dnndo.system.domain.dto.CampusNewsDTO
     */
    List<CampusNews> selectCampusNewsList(CampusNewsDTO dto);

    /**
     * 根据新闻ID获取详细信息
     * @param newsId 新闻唯一标识符
     * @return CampusNewsDTO 包含新闻详细信息的数据对象
     * @see com.dnndo.system.domain.dto.CampusNewsDTO
     */
    CampusNewsDTO selectCampusNewsById(Long newsId);

    /**
     * 修改已有校园新闻信息
     * @param campusNewsDTO 包含更新字段的新闻数据对象
     * @return int 受影响的数据库记录数，用于判断操作是否成功
     * @see com.dnndo.system.domain.dto.CampusNewsDTO
     */
    int updateCampusNewsById(CampusNewsDTO campusNewsDTO);

    /**
     * 新增校园新闻信息
     * @param campusNewsDTO 包含新增字段的新闻数据对象
     * @return int 受影响的数据库记录数，用于判断操作是否成功
     * @see com.dnndo.system.domain.dto.CampusNewsDTO
     */
    int insertCampusNews(CampusNewsDTO campusNewsDTO);

    /**
     * 删除指定ID的新闻信息
     * @param newsId 要删除的新闻唯一标识符
     * @return int 受影响的数据库记录数，用于判断操作是否成功
     * @see com.dnndo.system.domain.dto.CampusNewsDTO
     */
    int deleteCampusNewsById(Integer newsId);

    /**
     * 根据新闻id获取新闻的详细信息
     * @param newsId 新闻唯一标识符
     * @param language 语言类型（zh/en）
     * @return CampusNewsInfoVO 包含新闻详细信息的数据对象
     * @see com.dnndo.system.domain.vo.CampusNewsInfoVO
     */
    CampusNewsInfoVO selectCampusNewsByIdList(Integer newsId, String language);

    /**
     * 获取校园新闻列表
     * @param params 包含分页参数和查询条件的新闻查询对象
     * @return List<NewsVO> 校园新闻列表
     * @see com.dnndo.system.domain.vo.NewsVO
     */
    List<NewsVO> news(NewsDTO params);

    /**
     * 获取校园新闻总数
     * @param dto 包含查询条件的新闻查询对象
     * @return int 校园新闻总数
     * @see com.dnndo.system.domain.dto.NewsDTO
     */
    int countCampusNews(NewsDTO dto);

}
